About OpenTrials

From OpenTrials page: OpenTrials is a collaboration between Open Knowledge and Dr Ben Goldacre from the University of Oxford DataLab. It aims to locate, match, and share all publicly accessible data and documents, on all trials conducted, on all medicines and other treatments, globally.

In addition to web search, the OpenTrials database is also accessible via API, documented as Open API (Swagger) format.

This short tutorial shows how to use this API from R with rapiclient.

Issues

Report rapiclient bugs on rapiclient issues. Source R Markdown for this page is here.

Report errors with OpenTrials data (for example, if a trial has incorrect treatments tagged to it) on this page.

Preparation

Install rapiclient from Github:

devtools::install_github("bergant/rapiclient")

Use get_api and get_operations to create R client functions:

library(rapiclient)
open_trials_api <- get_api("http://api.opentrials.net/v1/swagger.yaml")
open_trials_schemas <- get_schemas(open_trials_api)
open_trials <- get_operations(open_trials_api, handle_response = content_or_stop)

names(open_trials)
##  [1] "searchTrials"        "autocomplete"        "searchFDADocuments" 
##  [4] "getTrial"            "getPublication"      "getCondition"       
##  [7] "getOrganisation"     "getRecords"          "getRecord"          
## [10] "getPerson"           "getIntervention"     "list"               
## [13] "listFDAApplications" "getFDAApplication"   "listDocuments"      
## [16] "getDocument"

Search Trials

searchTrials returns trials based on a search query. By default, it’ll search in all of a trial’s attributes. Parameter q is a ElasticSearch query string. Parameters page (1 to 100) and per_page (10 to 100) are optional.

trials <- open_trials$searchTrials(q='public_title:(depressive OR depression)')

trials$total_count
## [1] 4613
length(trials$items)
## [1] 20

There are 4613 trials matching this search query and the first 20 already waiting in the trials$items list.

Take a look at the richness of the trial search result schema before using the results:

library(DiagrammeR)
grViz(
  rapiclient::get_schema_graphviz_dot(
    open_trials_api, 
    open_trials_api$definitions$TrialSearchResults
  ) 
)

Print some of the trial attributes in a table:

library(dplyr)
library(knitr)

lapply(trials$items, function(x) { data.frame(
    title = gsub("\n","",x$public_title), 
    source_id = x$source_id,
    sample_size = ifelse(length(x$target_sample_size)==0, NA, x$target_sample_size),
    status = x$status,
    registered = format(as.POSIXct(x$registration_date)),
    publications = length(x$publications),
    stringsAsFactors = FALSE
)}) %>% 
  bind_rows %>% 
  kable(caption = "Table: some data from trials search result")
Table: some data from trials search result
title source_id sample_size status registered publications
Study of the Efficacy and Safety of Initial Administration of 17 mg Vortioxetine Intravenously With 10 mg/Day Vortioxetine Orally in Patients With Major Depressive Disorder nct 54 ongoing 2016-09-28 0
A Study to Evaluate the Efficacy, Safety and Tolerability of Fixed Doses of Intranasal Esketamine in Japanese Participants With Treatment Resistant Depression nct 183 ongoing 2016-09-27 0
Cost- Effectiveness and Quality of Life Assessment in Bipolar Disorder Depressive Episode nct 78 complete 2016-09-25 0
Measurement-based Care for Depression in Resource-Poor Settings nct 140 ongoing 2016-09-24 0
Dallas 2K: A Natural History Study of Depression nct 2000 ongoing 2016-09-23 0
Dynamic Learning in Depression nct 120 ongoing 2016-09-22 0
Magnetic Stimulation of the Brain in Schizophrenia or Depression nct 80 ongoing 2016-09-14 0
A Study to Investigate the Safety, Tolerability, and Pharmacodynamics of JNJ-54175446 in Participants With Major Depressive Disorder nct 64 ongoing 2016-09-13 0
Cost- Effectiveness and Quality of Life Assessment in Major Depression Disorder nct 68 complete 2016-09-11 0
Augmentation of Treatment-Resistant Depression With An Analog of the Neuroactive Steroid Allopregnanolone nct 10 ongoing 2016-09-09 0
A Study to Evaluate the Effects of a Single-Dose and Repeat-Administration of Intranasal Esketamine on On-Road Driving in Participants With Major Depressive Disorder nct 24 ongoing 2016-09-01 0
Neural and Cognitive Mechanisms of Depression and Anxiety: a Multimodal MRI Study nct 150 ongoing 2016-08-30 0
Oral ketamine for treating depression Orale ketamine als aanvullende behandeling bij patiënten met een therapieresistente depressie euctr NA ongoing 2016-08-30 0
Oral ketamine for treating depression Orale ketamine als aanvullende behandeling bij patiënten met een therapieresistente depressie euctr NA ongoing 2016-08-30 0
Development of objective measures for depression, bipolar disorder and dementia by quantifying facial expression, body movement, and voice data during clinical interview and daily activity utilizing wearable device ictrp 300 ongoing 2016-08-25 0
Augmenting Internet-Based Cognitive Behavioral Therapy for Major Depressive Disorder With Low-Level Light Therapy nct 200 ongoing 2016-08-24 0
The Impact of Three Distinct Exercise Types on Fatigue, Anxiety, and Depression in Parkinson’s Disease nct 32 ongoing 2016-08-24 0
CanDirect: Effectiveness of a Telephone-supported Depression Self-care Intervention for Cancer Survivors nct 286 ongoing 2016-08-24 0
Brain Function in Depression and Insulin Resistance nct 60 ongoing 2016-08-23 0
Repetitive Transcranial Magnetic Stimulationfor 2010 criteria diagnosed Fibromyalgia with a comorbidity of depression: Evidence from a pilot Randomized Sham-Controlled Study ictrp 40 ongoing 2016-08-22 0

Tips & Tricks

Print a function to see its documentation. For example:

open_trials$getTrial
## getTrial 
##  
## Description:
##    Returns a trial's details and related entities (e.g. `conditions`). 
## 
## Parameters:
##   id (string)
##     ID of the trial

If parameter name is a reserved word in R, quote it with backticks:

conditions <- 
  open_trials$autocomplete(`in` = "condition", q = "addiction", per_page = 100) %>% 
  getElement("items") %>% 
  bind_rows %>%  
  select(id, name)

Note that operations are not vectorised. You have to use the *apply functions to get the data for arguments with length > 1. For example, count the trials for each condition:

conditions$trials <- 
  sapply(conditions$id, function(x) {
    open_trials$searchTrials(q = sprintf("conditions.id:(%s)", x))[["total_count"]] 
  })  
  
conditions %>% arrange(desc(trials)) %>% top_n(30, wt = trials) %>% knitr::kable(.)
id name trials
12f8f74b-bff8-49ce-bba8-98268271f3b3 Opiate Addiction 53
0eec2750-8c1e-11e6-be70-0242ac12000f Addiction 49
f2a93773-ec26-4fa0-9f75-a5b920aac395 Drug Addiction 41
faa9dce0-8c2e-11e6-be70-0242ac12000f Nicotine addiction 33
a1bbbf9d-e64e-40be-89b8-6fa3418e583d Cocaine Addiction 30
0b2f9b78-8c1a-11e6-be70-0242ac12000f Smoking addiction 25
b96c69de-8c3b-11e6-be70-0242ac12000f Heroin addiction 20
3ff7db3d-07df-43eb-94d1-fef0a7bfe610 Opioid Addiction 14
1ba56d32-8c21-11e6-be70-0242ac12000f Tobacco Addiction 13
ee16cd52-238e-42b7-8556-a1c3d29e6e8c Alcohol Addiction 13
e84efb49-7b06-495a-8941-aba6a111ce3f Nicotine Addiction with the desire to quit smoking 13
0ee556e6-8c1e-11e6-be70-0242ac12000f Mental and Behavioural Disorders: Addiction 8
a63ceada-adc5-41a2-adcf-135dd9efe7f4 Exercise Addiction 7
81741e64-c26c-40e9-8c31-91e45ed1ebd0 Substance Addiction 5
40461e86-e5ff-4ec4-8c13-2636bdbcdc98 Internet Addiction 5
2ec0ff7b-562d-4482-967b-3a053281fba7 opium addiction 4
0e329957-3a71-4dc9-ad84-c9a3c4f5c453 Methamphetamine Addiction 4
65396a20-e73b-4c33-a154-8bb510b723b1 Addictions 3
5311bfed-a186-40fd-b50b-09407a195b65 Amphetamine Addiction 3
ba8aa58e-0e01-4fb8-9373-230b1f425f63 Opioid drug addiction 3
2cf7ee08-8d0b-11e6-988b-0242ac12000c Food Addiction 2
2ad535de-8cae-11e6-988b-0242ac12000c Cigarette Addiction 2
614a0bac-f698-4f9c-a40f-0728f9a2806e Smopking (nicotine addiction/Tobacco addiction) 2
7a23c9f0-2811-41ba-b43b-fa9dc9813353 pornographic addiction 2
8306af24-636a-4c82-aea3-c06738c09561 Narcotic Addiction 2
c9c2dd22-1f75-472d-974a-f632d092f9b8 treatment resistant heroin addiction 2
94a37d12-5a73-47aa-ab1d-2c1ec3b03cf9 Nicotine addiction/smoking 2
2cbed2c4-ae9a-498d-a278-94d717467fd8 Internet addiction disorder 2
36cf59ac-0b09-4d04-b5cc-76b71e44664b Patients with opioid addiction 2
d9c97b1c-c4b0-4a48-bc65-0b173130c94e Addiction to illicit heroin 2
1983ca29-118f-4213-a552-78298006ea87 Opiate addiction (detoxification from illicit opiates) 2
3f04b9b8-bbdc-42b6-95d2-ee044be66a42 Subjects have a diagnosis of opiate addiction 2
853f313c-83c8-4bb7-bc68-d2923862531c treatment of dependence in alcohol addiction 2

OpenTrials Operations

From Swagger definition (“http://api.opentrials.net/v1/swagger.yaml”)

searchTrials

Description: Returns trials based on a search query. By default, it’ll search in all of a trial’s attributes. - q is a ElasticSearch query string (e.g. public_title:(depressive OR depression)) - page can take a value between 1 and 100 - per_page can take a value between 10 and 100

autocomplete

Description: Autocomplete search feature for supported database entities (condition, intervention, location, person, organisation). It has the same options as a regular search operation, with an extra required in parameter indicating the entity type to search.

searchFDADocuments

Description: Search the FDA documents

getTrial

Description: Returns a trial’s details and related entities (e.g. conditions).

getPublication

Description: Returns publication details

getCondition

Description: Returns condition details

getOrganisation

Description: Returns organisation details

getRecords

Description: Returns a trial’s raw records from its sources

getRecord

Description: Returns a trial’s raw record from its sources

getPerson

Description: Returns person details

getIntervention

Description: Returns intervention details

list

Description: Returns list of sources

listFDAApplications

Description: Returns FDA applications

getFDAApplication

Description: Returns an FDA application details

listDocuments

Description: Returns documents

getDocument

Description: Returns details of a document

List of Data Sources

OpenTrials data sources:

sources <- open_trials$list()
knitr::kable(bind_rows(sources), caption = "Table of sources")
Table of sources
id name source_url type terms_and_conditions_url
fda U.S. Food and Drug Administration http://www.fda.gov other NA
cochrane_schizophrenia Cochrane Schizophrenia Group http://schizophrenia.cochrane.org/ other NA
hra Health Research Authority http://www.hra.nhs.uk other http://www.hra.nhs.uk/terms-conditions/
fdadl FDA Drug Labels https://open.fda.gov other https://open.fda.gov/terms/
icdcm ICD-CM https://www.cms.gov/Medicare/Coding/ICD10/index.html other NA
icdpcs ICD-PCS https://www.cms.gov/Medicare/Coding/ICD10/index.html other NA
pubmed PubMed http://www.ncbi.nlm.nih.gov/pubmed other https://www.ncbi.nlm.nih.gov/home/about/policies.shtml
euctr EU Clinical Trials Register https://www.clinicaltrialsregister.eu register https://www.clinicaltrialsregister.eu/disclaimer.html
ictrp WHO ICTRP http://www.who.int/trialsearch/ register http://www.who.int/ictrp/search/download/en/
nct ClinicalTrials.gov https://clinicaltrials.gov register https://clinicaltrials.gov/ct2/about-site/terms-conditions

R Packages

Attached packages:

sessionInfo()$otherPkgs %>%
  names %>% 
  lapply(citation) %>% 
  lapply(first) %>% 
  lapply(print, style = "html") %>% 
  invisible

Xie Y (2016). knitr: A General-Purpose Package for Dynamic Report Generation in R. R package version 1.14, http://yihui.name/knitr/.

Wickham H and Francois R (2015). dplyr: A Grammar of Data Manipulation. R package version 0.4.3, https://CRAN.R-project.org/package=dplyr.

Sveidqvist K, Bostock M, Pettitt C, Daines M, Kashcha A and Iannone R (2016). DiagrammeR: Create Graph Diagrams and Flowcharts Using R. R package version 0.8.3, https://github.com/rich-iannone/DiagrammeR.

Bergant D (2016). rapiclient: Dynamic Open API (Swagger) Client. R package version 0.1.0.9004, https://github.com/bergant/rapiclient.

Other loaded packages in R session

sessionInfo()$loadedOnly %>%
  lapply(function(x) paste(x$Package, x$Version, x$URL)) %>% 
  paste(collapse = " - ") %>% 
  cat

Rcpp 0.12.7 http://www.rcpp.org, http://dirk.eddelbuettel.com/code/rcpp.html, https://github.com/RcppCore/Rcpp - rstudioapi 0.5 - magrittr 1.5 - munsell 0.4.3 - colorspace 1.2-6 - R6 2.2.0 https://github.com/wch/R6/ - highr 0.6 https://github.com/yihui/highr - stringr 1.0.0 - httr 1.2.1 https://github.com/hadley/httr - plyr 1.8.3 http://had.co.nz/plyr, https://github.com/hadley/plyr - visNetwork 0.2.1 https://github.com/DataKnowledge/visNetwork - tools 3.2.5 - parallel 3.2.5 - rsvg 0.5 https://github.com/jeroenooms/rsvg https://www.opencpu.org/posts/svg-release - DBI 0.5-1 http://rstats-db.github.io/DBI - htmltools 0.3.5 https://github.com/rstudio/htmltools - lazyeval 0.2.0 - yaml 2.1.13 - assertthat 0.1 - digest 0.6.10 http://dirk.eddelbuettel.com/code/digest.html - tibble 1.2 https://github.com/hadley/tibble - formatR 1.4 http://yihui.name/formatR - htmlwidgets 0.7 https://github.com/ramnathv/htmlwidgets - codetools 0.2-14 - curl 2.1 https://github.com/jeroenooms/curl#readme - evaluate 0.9 https://github.com/hadley/evaluate - rmarkdown 1.1 http://rmarkdown.rstudio.com - stringi 1.0-1 http://stringi.rexamine.com/ http://site.icu-project.org/ http://www.unicode.org/ - scales 0.4.0 https://github.com/hadley/scales - jsonlite 1.1 http://arxiv.org/abs/1403.2805, https://www.opencpu.org/posts/jsonlite-a-smarter-json-encoder